home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / CrtCommand.3 < prev    next >
Text File  |  1994-09-20  |  10KB  |  265 lines
  1.  
  2.  
  3.  
  4. Tcl_CreateCommand(3) Tcl Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_CreateCommand,  Tcl_DeleteCommand,   Tcl_GetCommandInfo,
  12.      Tcl_SetCommandInfo - implement new commands in C
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      Tcl_CreateCommand(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _d_e_l_e_t_e_P_r_o_c)
  18.  
  19.      int
  20.      Tcl_DeleteCommand(_i_n_t_e_r_p, _c_m_d_N_a_m_e)
  21.  
  22.      int                                                           |
  23.      Tcl_GetCommandInfo(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _i_n_f_o_P_t_r)                  |
  24.  
  25.      int                                                           |
  26.      Tcl_SetCommandInfo(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _i_n_f_o_P_t_r)                  |
  27.  
  28. ARGUMENTS
  29.      Tcl_Interp          *_i_n_t_e_r_p           (in)      Interpreter
  30.                                                      in  which to
  31.                                                      create   new
  32.                                                      command.
  33.  
  34.      char                *_c_m_d_N_a_m_e          (in)      Name of com-
  35.                                                      mand.
  36.  
  37.      Tcl_CmdProc         *_p_r_o_c             (in)      Implementation
  38.                                                      of  new com-
  39.                                                      mand:   _p_r_o_c
  40.                                                      will      be
  41.                                                      called when-
  42.                                                      ever _c_m_d_N_a_m_e
  43.                                                      is   invoked
  44.                                                      as   a  com-
  45.                                                      mand.
  46.  
  47.      ClientData          _c_l_i_e_n_t_D_a_t_a        (in)      Arbitrary
  48.                                                      one-word
  49.                                                      value     to
  50.                                                      pass to _p_r_o_c
  51.                                                      and
  52.                                                      _d_e_l_e_t_e_P_r_o_c.
  53.  
  54.      Tcl_CmdDeleteProc   *_d_e_l_e_t_e_P_r_o_c       (in)      Procedure to
  55.                                                      call  before
  56.                                                      _c_m_d_N_a_m_e   is
  57.                                                      deleted from
  58.                                                      the   inter-
  59.                                                      preter;
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_CreateCommand(3) Tcl Library Procedures
  71.  
  72.  
  73.  
  74.                                                      allows   for
  75.                                                      command-
  76.                                                      specific
  77.                                                      cleanup.  If
  78.                                                      NULL,   then
  79.                                                      no procedure
  80.                                                      is    called
  81.                                                      before   the
  82.                                                      command   is
  83.                                                      deleted.
  84.  
  85.      Tcl_CmdInfo         *_i_n_f_o_P_t_r          (in/out)  Pointer   to  |
  86.                                                      structure  |
  87.                                                      containing  |
  88.                                                      various  |
  89.                                                      information  |
  90.                                                      about  a Tcl  |
  91.                                                      command.
  92. _________________________________________________________________
  93.  
  94.  
  95. DESCRIPTION
  96.      Tcl_CreateCommand defines a new command in _i_n_t_e_r_p and  asso-
  97.      ciates  it with procedure _p_r_o_c such that whenever _c_m_d_N_a_m_e is
  98.      invoked as a Tcl command (via a call to  Tcl_Eval)  the  Tcl
  99.      interpreter will call _p_r_o_c to process the command.  If there
  100.      is already a command  _c_m_d_N_a_m_e  associated  with  the  inter-
  101.      preter,  it  is  deleted.   _P_r_o_c  should  have arguments and
  102.      result that match the type Tcl_CmdProc:
  103.           typedef int Tcl_CmdProc(
  104.                ClientData _c_l_i_e_n_t_D_a_t_a,
  105.                Tcl_Interp *_i_n_t_e_r_p,
  106.                int _a_r_g_c,
  107.                char *_a_r_g_v[]);
  108.      When _p_r_o_c is invoked the _c_l_i_e_n_t_D_a_t_a  and  _i_n_t_e_r_p  parameters
  109.      will  be copies of the _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p arguments given
  110.      to Tcl_CreateCommand.  Typically, _c_l_i_e_n_t_D_a_t_a  points  to  an
  111.      application-specific  data  structure that describes what to
  112.      do when the command procedure is  invoked.   _A_r_g_c  and  _a_r_g_v
  113.      describe  the  arguments  to  the  command,  _a_r_g_c giving the
  114.      number of arguments (including the command  name)  and  _a_r_g_v
  115.      giving  the  values  of  the arguments as strings.  The _a_r_g_v
  116.      array will contain _a_r_g_c+1  values;  the  first  _a_r_g_c  values
  117.      point to the argument strings, and the last value is NULL.
  118.  
  119.      _P_r_o_c must return an integer  code  that  is  either  TCL_OK,
  120.      TCL_ERROR,  TCL_RETURN, TCL_BREAK, or TCL_CONTINUE.  See the
  121.      Tcl overview man page for details on what these codes  mean.
  122.      Most  normal  commands will only return TCL_OK or TCL_ERROR.
  123.      In addition, _p_r_o_c must set  _i_n_t_e_r_p->_r_e_s_u_l_t  to  point  to  a
  124.      string value; in the case of a TCL_OK return code this gives
  125.      the result of the command, and in the case of  TCL_ERROR  it
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_CreateCommand(3) Tcl Library Procedures
  137.  
  138.  
  139.  
  140.      gives  an  error  message.  The Tcl_SetResult procedure pro-
  141.      vides an easy interface for setting the return  value;   for
  142.      complete details on how the _i_n_t_e_r_p->_r_e_s_u_l_t field is managed,
  143.      see the Tcl_Interp man page.  Before invoking a command pro-
  144.      cedure,  Tcl_Eval  sets  _i_n_t_e_r_p->_r_e_s_u_l_t to point to an empty
  145.      string, so simple commands can return  an  empty  result  by
  146.      doing nothing at all.
  147.  
  148.      The contents of the _a_r_g_v array belong to  Tcl  and  are  not  |
  149.      guaranteed  to  persist  once _p_r_o_c returns:  _p_r_o_c should not  |
  150.      modify them, nor should it set _i_n_t_e_r_p->_r_e_s_u_l_t to point  any-  |
  151.      where  within  the  _a_r_g_v  values.   Call  Tcl_SetResult with  |
  152.      status TCL_VOLATILE if you want to return something from the  |
  153.      _a_r_g_v array.
  154.  
  155.      _D_e_l_e_t_e_P_r_o_c will be invoked when  (if)  _c_m_d_N_a_m_e  is  deleted.
  156.      This  can  occur  through  a  call  to  Tcl_DeleteCommand or
  157.      Tcl_DeleteInterp, or by replacing _c_m_d_N_a_m_e in another call to
  158.      Tcl_CreateCommand.  _D_e_l_e_t_e_P_r_o_c is invoked before the command
  159.      is deleted, and gives  the  application  an  opportunity  to
  160.      release   any   structures   associated  with  the  command.
  161.      _D_e_l_e_t_e_P_r_o_c should have arguments and result that  match  the
  162.      type Tcl_CmdDeleteProc:
  163.  
  164.           typedef void Tcl_CmdDeleteProc(ClientData _c_l_i_e_n_t_D_a_t_a);
  165.  
  166.      The _c_l_i_e_n_t_D_a_t_a argument will be the same as  the  _c_l_i_e_n_t_D_a_t_a
  167.      argument passed to Tcl_CreateCommand.
  168.  
  169.      Tcl_DeleteCommand deletes a command from  a  command  inter-
  170.      preter.  Once the call completes, attempts to invoke _c_m_d_N_a_m_e
  171.      in _i_n_t_e_r_p will result in errors.  If _c_m_d_N_a_m_e isn't bound  as
  172.      a  command in _i_n_t_e_r_p then Tcl_DeleteCommand does nothing and
  173.      returns -1;  otherwise it returns 0.  There are no  restric-
  174.      tions  on  _c_m_d_N_a_m_e:   it may refer to a built-in command, an
  175.      application-specific command, or a Tcl procedure.
  176.  
  177.      Tcl_GetCommandInfo checks to see whether its  _c_m_d_N_a_m_e  argu-  |
  178.      ment  exists as a command in _i_n_t_e_r_p.  If not then it returns  |
  179.      0.  Otherwise it places information about the command in the  |
  180.      structure  pointed to by _i_n_f_o_P_t_r and returns 1.  Tcl_CmdInfo  |
  181.      structures  have  fields   named   _p_r_o_c,   _c_l_i_e_n_t_D_a_t_a,   and  |
  182.      _d_e_l_e_t_e_P_r_o_c, which have the same meaning as the corresponding  |
  183.      arguments to  Tcl_CreateCommand.   There  is  also  a  field  |
  184.      _d_e_l_e_t_e_D_a_t_a,  which  is  the  ClientData  value  to  pass  to  |
  185.      _d_e_l_e_t_e_P_r_o_c;  it is normally the same as _c_l_i_e_n_t_D_a_t_a  but  may  |
  186.      be set independently using the Tcl_SetCommandInfo procedure.  |
  187.  
  188.      Tcl_SetCommandInfo is used  to  modify  the  procedures  and  |
  189.      ClientData  values  associated  with a command.  Its _c_m_d_N_a_m_e  |
  190.      argument is the name of a command in _i_n_t_e_r_p.  If  this  com-  |
  191.      mand  exists  then Tcl_SetCommandInfo returns 0.  Otherwise,  |
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tcl_CreateCommand(3) Tcl Library Procedures
  203.  
  204.  
  205.  
  206.      it copies the information from *_i_n_f_o_P_t_r  to  Tcl's  internal  |
  207.      structure  for  the  command  and returns 1.  Note that this  |
  208.      procedure allows the ClientData  for  a  command's  deletion  |
  209.      procedure  to be given a different value than the ClientData  |
  210.      for its command procedure.
  211.  
  212.  
  213. KEYWORDS
  214.      bind, command, create, delete, interpreter
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tcl                                                             4
  262.  
  263.  
  264.  
  265.